<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
  <head>
    <title>Ant-contrib Tasks: Relentless</title>
  </head>

  <body>
    <h1>Relentless</h1>

    <p>The &lt;relentless&gt; task will execute all of the
    nested tasks, regardless of whether one or more of the
    nested tasks fails.  When &lt;relentless&gt; has completed
    executing the nested tasks, it will either
    <ul>
        <li>fail, if any one or more of the nested tasks failed; or
        <li>succeed, if all of the nested tasks succeeded.
    </ul>
    An appropriate message will be written to the log.
    </p>
    <P>
    Tasks are executed in the order that they appear within the
    &lt;relentless&gt; task.  It is up to the user to ensure that
    relentless execution of the
    nested tasks is safe.
    </p>
    <p><em>
      This task only works for ant version greater than or equal
      to ant 1.6.0.
      </em>
    </p>

    <h2>Parameters</h2>
    <table border="1" cellpadding="2" cellspacing="0">
      <tr>
        <th>Attribute</th>
        <th>Description</th>
        <th>Required</th>
      </tr>
      <tr>
        <td valign="top">description</td>
        <td valign="top">A string that will be included in the log output.  This
        can be useful for helping to identify sections of large Ant builds.</td>
        <td align="center" valign="top">No</td>
      </tr>
      <tr>
        <td valign="top">terse</td>
        <td valign="top">Setting this to <code>true</code> will eliminate some of the progress
        output generated by &lt;relentless&gt;.  This can reduce clutter in some
        cases.  The default value is <code>false</code>.</td>
        <td align="center" valign="top">No</td>
      </tr>
    </table>

    <h2>Nested elements</h2>

    <h3>task list</h3>

    <p>
    The only nested element supported by &lt;relentless&gt; is a list of tasks
    to be executed.  At least one task must be specified.
    </p>
    <P>
    It is important to note that &lt;relentless&gt; only proceeds relentlessly
    from one task to the next - it does <b>not</b> apply recursively to any tasks
    that might be invoked by these 
    nested tasks.  If a nested task invokes some other list of tasks (perhaps
    by &lt;antcall&gt; for example), and one of those other tasks fails, then the
    nested task will stop at that point.
    </p>
    
    <h3>Example</h3>
    <p>
      A relentless task to print out the first five canonical variable names:
    <blockquote>
      <pre>&lt;relentless description="The first five canonical variable names."&gt;
    &lt;echo&gt;foo&lt;/echo&gt;
    &lt;echo&gt;bar&lt;/echo&gt;
    &lt;echo&gt;baz&lt;/echo&gt;
    &lt;echo&gt;bat&lt;/echo&gt;
    &lt;echo&gt;blah&lt;/echo&gt;
&lt;/relentless&gt;</pre>
      </blockquote>
      which should produce output looking more or less like
    <blockquote>
      <pre>[relentless] Relentlessly executing: The first five canonical variable names.
[relentless] Executing: task 1
     [echo] foo
[relentless] Executing: task 2
     [echo] bar
[relentless] Executing: task 3
     [echo] baz
[relentless] Executing: task 4
     [echo] bat
[relentless] Executing: task 5
     [echo] blah
[relentless] All tasks completed successfully.</pre>
      </blockquote>
      </p>
      If you change the first line to set the <code>terse</code> parameter, 
      <pre>    &lt;relentless terse="true" description="The first five canonical variable names."/&gt;</pre>the
      output will look more like this:
    <blockquote>
      <pre>[relentless] Relentlessly executing: The first five canonical variable names.
     [echo] foo
     [echo] bar
     [echo] baz
     [echo] bat
     [echo] blah
[relentless] All tasks completed successfully.</pre>
      </blockquote>
      </p>
      <p>
        If we change the third task to deliberately fail
    <blockquote>
      <pre>&lt;relentless terse="true" description="The first five canonical variable names."&gt;
    &lt;echo&gt;foo&lt;/echo&gt;
    &lt;echo&gt;bar&lt;/echo&gt;
    &lt;fail&gt;baz&lt;/fail&gt;
    &lt;echo&gt;bat&lt;/echo&gt;
    &lt;echo&gt;blah&lt;/echo&gt;
&lt;/relentless&gt;</pre>
      </blockquote>
        then the output should look something like this.
    <blockquote>
      <pre>[relentless] Relentlessly executing: The first five canonical variable names.
     [echo] foo
     [echo] bar
[relentless] Task task 3 failed: baz
     [echo] bat
     [echo] blah

BUILD FAILED
/home/richter/firmware/sensor/build.xml:1177: Relentless execution: 1 of 5 tasks failed.</pre>
        </blockquote>
      </p>
    <hr>
    <p align="center">Copyright &copy; 2005 Ant-Contrib Project. All
    rights Reserved.</p>

  </body>
</html>
